<?php
/**
 *	KLF Framework
 *
 *	@author Kristian Oye <kristianoye@gmail.com> 
 *	@copyright (C) 2010-2011, Kristian Oye
 */
namespace KLF\System\Web\Routing
{
	use KLF\KCore;
	use KLF\System\KObject;
	use KLF\System\Collections\KList;
	use KLF\System\Web\Routing\KRouteHandler;
	use KLF\System\Errors\KInvalidOperationException;
	
	/**
	 *  Class KRouteData
	 *
	 *  @package KLF\System\Web\Routing
	 *  @access public
	 *  @author Kristian Oye <kristianoye@gmail.com>
	 *  @since 0.1
	 *  
	 *  @method KRouteData NewInstance
	 *  
	 *  @property KRouteDictionary $DataTokens A collection of matched tokens.
	 *  @property KRoute $Route The route that was matched to.
	 *  @property \KLF\System\Web\Routing\KRouteHandler $RouteHandler
	 *  @property KRouteDictionary $Values A collection of matched tokens.
	 *  @property \KLF\System\Collections\KList $ValuesByPosition
	 */
	class KRouteData extends KObject
	{
		/**
		 * 
		 * @var KRouteDictionary $_propDataTokens
		 */
		protected $_propDataTokens;
		
		/**
		 * 
		 * @var KRoute $_propRoute
		 */
		protected $_propRoute;
		
		/**
		 * The handler that fascilitates the transition
		 * 
		 * @var KRouteHandler $_propRouteHandler
		 */
		protected $_propRouteHandler;
		
		/**
		 * 
		 * @var KRouteDictionary $_propValues
		 */
		protected $_propValues;
		
		/**
		 * Stores the values collected by position.
		 * 
		 * @var KList $_propValuesByPosition
		 */
		protected $_propValuesByPosition;
		
		/**
		 * Creates a new KRouteData object
		 *
		 * @author Kristian Oye <kristianoye@gmail.com>
		 * @since 0.1
		*/
		public function __construct(KRoute $route, $handler)
		{
			$this->_propRoute = $route;
			$this->_propValues = new KRouteDictionary();
			$this->_propDataTokens = new KRouteDictionary();
			$this->_propValuesByPosition = new KList();
			$this->_propRouteHandler = $handler;
		}
		
		/**
		 * Gets a required string from the collected values or
		 * throws an exception if it does not exist or is empty.
		 * 
		 * @param string $vname The key into the collection.
		 * 
		 * @throws KInvalidOperationException
		 */
		public function GetRequiredString($vname)
		{
			if (is_string($vname))
			{
				if (isset($this->_propValues[$vname]))
				{
					$result = $this->_propValues[$vname];
					
					if (is_string($result) && strlen($result) > 0)
					{
						return $result;
					}
					else
					{
						throw new KInvalidOperationException(
							KCore::FS("Required key '{keyName}' was not in route values.",
								array('keyName' => $vname)));
					}
				}
			}
			throw new KInvalidOperationException(
				KCore::FS("Required key '{keyName}' was not in route values.",
					array('keyName' => $vname)));
		}
	}
}
